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Small Doc Web Serving 


I n our June and September 1995 columns, we intro¬ 
duced a hyper-literate programming system we call 
"SmallDoc." In the last two issues, we sketched out how 
to turn SmallDoc into HTML, and howto build a generic 
TCP/1P server framework. This issue ties it all together so 
you can begin serving your Smalltalk project documenta¬ 
tion to anyone with a Web browser. 

The generic TCP/IP server described earlier needs only 
oneortwo blocks of Smalltalk code in order to implement 
a complete server. A message is sent to the class that asso¬ 
ciates a "service” block with a port number, and a second, 
opti onal (but strongly encou raged!) message is sent to the 
class to associatean "exception" block with the same port 
number. 

For example, a simple hypertext service can be imple¬ 
mented by adding the following method to the TcpServer 
class that we presented last month: 

TcpServer class: 

initializeForHttpd 

"Set up a service and exception handler suitable for 
servicing World Wide Web requests." 

selfdefaultHandlerFor: 80 is: [exception :stream| 
stream httpChattyHandle: exception]; 
defauItServiceFor: 80 is:[:stream | 
stream htmlForSmallDocRequest] 

httpd 

"Answer the default hypertext transport protocol server." 
''self onPort: 80 

Now, to start up a Hypertext Transfer Protocol server all 
you need to do is evaluate "TcpServer httpd." Of course, 
if you do that right now it will crash, because we haven’t 
really written the handler or service blocks yet. 

If you are on a UNIX machine, remember that port 80 
is privileged — you will have to run Smalltalk as root to 
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run this service. If that is not possible, choose some other 
port above 1024, such as 8080. 

When an error is encountered in the server, it should 
alert the client so that things can be fixed. Our 
httpChattyHandle:for: method assumes the person using the 
Web browser might know something about Smalltalk, and 
so it sends contextual information back to the client. For 
non-developers, you might want to simplify this by report¬ 
ing only that an error occurred. 

PositionableStream 

httpChattyHandle: exception 
"Upon trouble with the request, attempt to send 
back a contextual information from <exception> in HTML 
format on <stream>." 

I ctx | 
self 

cr; nextPutAII: ‘HTTP/ 1.0 500'; cr; 
nextPutAII: 'Server:'; nextPutAII: (TcpServer 
signaturel n: TcpServer controller); cr; cr; 

n ext P u t A11:' <H TM L ><H E A D ><TI TLE>Unhandled 
exception!</ TlTLE ><l H EADxBODYxH 1>'; 
nextPutAII: exception errorstring; 
nextPutAII: '</ HlxP>Your request had a 
problem. Please copy the following stack and mail it to 
the<A HREF="mailto:' 

nextPutAII: (EmUser cal led: 'Su pervisor') 
networkName; 

nextPutAII: '“>ENVY Library 
Supervisors/ A>.</ P>'. 

ctx : = exception thisContext. 

5 timesRepeat: 

[ctx — nil ifFalse: 

[self print: ctx;cr]]. 

self nextPutAII:'</ BODY></ HTML>'; cr; flush 

Also, thisexamplerelieson ENVY repository information to 
report the server version information, and to obtain the 
email address of the repository supervisor. You should use 
suitable substitutes if you use a different code manage¬ 
ment system. 

SERVICING REQUESTS 

Now that we can handle failed requests, we should think 
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about servicing real requests! When the TcpServer sends 
html ForSmal I DocRequest to the socket stream, the stream 
may contai n "GET" a space, and the U RL the user entered 
or clicked. 

There is much more information in the typical HTTP 
request, and this method can easily become complex. If 
you want to process more of the request information, be 
sure to factorthis method into smaller methodsthat han¬ 
dle particular request information. 

In particular, this method only attempts to deal with 
"GET" requests, which is the normal way a Web browser 
passively requests a Web page This method does not han¬ 
dle "POST" requests, which is how a Web browser passes 
information entered by the remote user. 

PositionableStream 

htmIForSmallDocRequest 

"Assume I am a bi-directional stream on a socket 
that is connected to a web browser. Process an incoming 
SmallDoc GET request." 

| line path | 

[(line : = self nextLine) size >0]whileTrue: 

[('GET' occursln: line at: 1) ifTrue: 

[path := line copyFrom: 5 to: line size]]. 

self nextPutAII: ‘HTTP/ 1.0 200'; 

nextPutAII: 'Server: ';nextPutAII: (TcpServer 
signatureln: TcpServer controller); cr; cr; 

(path size =0 or: [path = '/ ']) 
ifTrue: [self httpHomePage] 
ifFalse: [self htmISmalIDocGet: path] 

This method looks for a line in the socket stream that 
begi ns with GET, and saves the rest of the Iine as the U RL 
to fetch. If the URL is empty or if it is a single slash, then 
some form of home page information should be sent back 
to theWeb browser, followed by closing the stream, which 
lets theWeb browser know the request is complete. 

PositionableStream 

httpHomePage 

"An empty GET request is received,so give a hearty 
welcome." 

self 

nextPutAII: 'This is an exercise for the reader. 

Put some literal HTML here (or some Text asHtml!)that 
explains how to navigate through your Smalltalk 
documentation repository.'; 
close 

If the U RL is not empty, there’s more work to do. We fol¬ 
low ENVY's existing structure for navigation; if you are 
using some other source code management system, you 
will have to implement a navigation strategy for your 
repository. 

We expect the fi rst component of the U RL to be a nam¬ 
ing root that serves as a dispatcher for the remainder of 
the URL. 


PositionableStream 

htmISmal IDocGet: pathstring 

"Place on myself valid top-level HTML for the given 
<pathString>, which must begin with a slash ($/), and 
therefore must have a size greater than zero, and must 
consist of URLized path from some naming root, separated 
by slashes. 

Valid roots are: 

1) Smalltalk, 

2) EmUser, 

3) EmConfiguration Map, 

4) Application, or 

5) SubApplication. 

The second component of the path is always one of 
the names that a root knows about. What follows is 
dependent on processing by the root, which is sent the 
rest of the path to play with. 

A new root must either be handled by this method, 
or it must be a global, and it must supply the methods 
#htmlAsRootOn:, and #htmlForPath:on:. 

This does minimal error checking -it assumes a 
handler will catch exceptions." 

| path root | 

"Parse the path, keeping the result." 

path :=pathRequest splitOn: $/. 

root : = Smalltalk at: path first asSymbol. 

1 = path size 
ifTrue: 

[self nextPutAII: 'Pragma: no-cache'; cr; cr. 
root htmlAsRootOn: self] 
ifFalse: 

[root htmIForPath: path on: self] 

Now we have a "naming root" that can be used for navi¬ 
gation, and all that is left to do is implement htmlAsRootOn: 
and html ForPath :on: so that any global can serve Web infor¬ 
mation. For example, a simple inspector can be imple¬ 
mented by making "Smalltalk" a naming root by imple¬ 
menting htmlAsRootOn:. 

SystemDictionary 

htmlAsRootOn: stream 

“Place on the given <stream> HTML links for my 
distinguished instances." 

stream htmlTitleAndHl: 'Smalltalk Globals'. 

"'(self keys asSortedCollection 
inject: stream 

into: [:stream :globall\lame | | global | 
global : = Smalltalk at: global Name, 
stream 

nextPutAII: '<A HREF-'/Smalltalk/'; 
nextPutAII: globalName; nextPutAII: '">'; 

nextPutAII: globalName; nextPutAII: '</A>‘. 
global class isMeta 
ifTrue: 

[stream nextPutAII: '(a class'. 
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(global class instSize > Object class 
instSize or: [global classPool size > 0])ifTrue: 

[stream nextPutAII: ' with state'], 
stream nextPutAII: ')<BR>'] 
ifFalse: [stream nextPutAII: '(an instance 
ofprint: global class; nextPutAII:')<BR>']. 
stream]) htmICIoseBody 

Now if htmIForPath:on: is implemented in Object, you can 
inspect arbitrary objects from a Web browser. This 
method uses a number of stream utility methods that 
make the task easier, by providing pre-assembled snip¬ 
pets of commonly used HTML. 

PositionableStream 
htmIBody: an Object 

"Place on myself the proper HTML to make 
<anObject> appear as body text. This must be preceded by 
a 'title' statement. Answer myself." 

self nextPutAII: '<BODY>'; htmIFonan Object; 
htmICIoseBody 

htmICIoseBody 

"Place on myself the proper HTML to close off a 
'body' statement. Answer myself." 

self nextPutAII: '</ BODY></ HTML>' 

htmITitle: string 

"Place on myself the proper HTML to make <string> 
a title. This must be followed by a 'body' statement. 

Answer myself." 

self nextPutAII:'<HTMLxHEADxTITLE>'; 
nextPutAII: string; nextPutAII:'<TlTLE></ HEAD>' 

htmlTitleAndHl: string 

"Place on myself the proper HTML to make <string> 
a title, followed by a 'body' statement and <string> as a 
top-level heading. Answer myself." 

self 

htmITitle: string; 
nextPutAII: '<BODYxHl>'; 
nextPutAII: string; 
nextPutAII: '</ Hl>' 

It would be easy to slip into gratuitous serving of all sorts 
of objects over the Web at this point, but we’d neglect our 
primary purpose: to serve Smalltalk project documenta¬ 
tion over the Web. To do this, we need to allow 
SubApplication to function as a naming root. (Since 
Application is a subclass of SubApplication, this also 
allows Application to serve as a naming root.) 

SubApplication class 

htmlAsRootOn: stream 

"Place on the given <stream> HTML links for all 


subapps or apps." 

stream htmlTitleAndHl: self name, 's'. 

''(self allNames asSortedCollection 
inject: stream 
into: [:stream :appl\lame | 
stream 

nextPutAII: '<A HREF-'/'; print: self; 

nextPut: $/; 

nextPutAII: appName; nextPutAII: 
nextPutAII: appName; nextPutAII: 

'</ AxBR>'. 

stream]) htmICIoseBody 

Now when a URL with a naming root, such as 
<http://yourhost/Appiication>, is entered into a 
Web browser, a page is returned that listsall Applications in 
the repository, together with links that have the next path 
component filled in. When oneofthelistedApp//cat/onsis 
clicked in the Web browser, the following method issentin 
the Smal I Doc server: 

SubApplication class 

htmIForPath: path on: stream 

"Place HTML for my components described by 
<path>on the <stream>." 

| component | 

2 = path size ifTrue: 

["This is dynamic information - do not cache it 
in the client." 

stream nextPutAII: 'Pragma:no-cache'; cr; cr. 
self htmlEditionsForName: path last on: stream] 

ifFalse: 

[(path last conform: [:ch | ch isDigit]) ifTrue: 

[path at: path size put: (Integer readFrom: path 
last readStream)]. 

component : = (Smalltalk classAt: path first) 
hrefToLibraryComponentFor: path. 

component isVersion ifFalse:[stream nextPutAII: 
'Pragma: no-cache'; cr], 
stream cr. 

3 = path size ifTrue: 

[stream htmIBody: 

(component commentOrTemplateln: component)] ifFalse: 
[4 = path size ifTrue: 

[stream htmIBody: (component 
commentOrTemplateln: component application)] ifFalse: 

[5 = path size ifTrue: 

[stream htmIBody: component comment] ifFalse: 
"path size >5 ifTrue:" 

[stream error: 'bad URL']]]] 

This method is a case statement. Only one of the ''path 
size” cases will be evaluated in anygiven invocation. Also 
note that if the last component of the path consists of 
digits, it is converted to an Integer. 

This sends two methods that we’re going to have to 

continued on page36 
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leave you to implement yourself, dueto space constraints. 
The SubApplication method html EditionsForName:on: needs 
to obtain all the editions for the SubAppli cation named by 
the second part of the path, and render them into the 
proper HTML so they will appear as links in the Web 
browser. For example, if the Web browser user typed or 
clicked <http : //yourhost/Application/Kernel>, 
the server should place links for each edition of Kernel on 
the socket stream. 

The more interesting method to complete is 
hrefToLibraryComponentFor:, which takes a collection of com¬ 
ponent parts and fetches the proper component out of the 
repository. For example, the URL <http://yourhost/ 
Kernel/Object/at:put:/3016057369> should cause 
the comment for the Object method at: put: with the edition 
time stamp of J uly 29, 19961:42:49 am to be placed on the 
socket stream. 

As hinted by the code, our treatment of the URL 
depends on its number of path parts. For an individual 
repository component, such as an app, subapp, class, 
class extension, or method, the last part of the U RL path 
is always a second count from the component's time 
stamp, thus allowing you to browse version history from a 
Web browser. These i ntegers are meant to be "opaque ref¬ 
erences" — the user should never have to type them in; 
rather, they should be part of anchors that were generat¬ 
ed from lists of editions. 

Following the example of SubAppli cation, you can now 


easily add htmlAsRootOn: and htmlForPath:on: to EmUser 
and EmConfigurationMap, as well as any other global that 
you want to use as a "naming root" for serving arbitrary 
information from Smalltalk over the Web. 

SATISFYING WITHOUT COMPROMISING 

This completes our series on putting your Smal Ital k project 
documentation on the Web. This series enables our princi¬ 
ples of hyper-1 iterate programming by ensuring that: 

1) the documentation forathing ison the same 
conceptual level as that thing; 

2) the documentation for a thing constantly and 
accu rately descri bes that thi ng; 

3) the documentation forathing is accessible by 
creators, their peers, re-users, reviewers, end-user 
documenters, and the merely curious; and 

4) the documentation for a thing is measurable, 
quantitatively and especially qualitatively. 

In addition, we hope we’ve shown you a few useful things 
about developi ng frameworks and automatical ly generat- 
ingHTML. 

Maintaining your documentation in your Smalltalk 
repository while exporting it "live” to Web browsers will 
satisfy the needs of external parties without compromis¬ 
ing the efficiency of your development team. 

Next month, we'll explore a topic close to our hearts — 
the use and abuse of Smalltalk mentors. S 



